Release 10.1A: OpenEdge Development:
ProDataSets

Filling the entire ProDataSet

To fill the ProDataSet as a whole (that is, traverse through each of its member buffers) use the method on the ProDataSet handle, as in this example:

hDSOrder:FILL().

Or without using a HANDLE variable:

DATASET dsOrder:FILL().

Note: There is no static FILL DATASET statement, but the second form of the FILL method makes it easy to execute on a static ProDataSet without explicitly having to retrieve its handle separately.

A FILL operation does not support any explicit batching or “chunking” of records in order to limit the size of a ProDataSet and the expense of filling it and passing it remotely as a parameter. However, you can define a query at any level of the ProDataSet to limit the number of records filled in one operation.

When applied to the ProDataSet handle, the FILL method finds all the top-level buffers in the ProDataSet, which are those that are not children in any active Data-Relation. This means that a child of a relation that has been deactivated is treated like a top-level buffer for a FILL of a ProDataSet. In this way you assure that a FILL on a ProDataSet touches every buffer in the ProDataSet.

The FILL method then starts a nested filling operation starting at each top-level buffer, paying attention to the Data-Relations for which the top buffer is the parent, and proceeds down through parent-child relationships recursively. If the buffer is a parent to any other buffer and the relation is active, the method gets each record in the parent, goes to each child of that parent and fills the child temp-table with those records related to the current parent, and cascades as it fills in further children down the hierarchy, before moving on to the next parent record.

If you want to fill a ProDataSet in a non-nested manner, that is, by loading all records at the top buffer level and then loading all records for that buffer’s children using a single query, you can do this by deactivating the relations (individually by setting each relation’s ACTIVE attribute to False or for the whole ProDataSet by setting its RELATIONS-ACTIVE attribute to False) and defining the appropriate query for the child that retrieves all records for all parents in a single pass. This might be more efficient under some circumstances. You’ll learn more about using these attributes in Chapter 5, " ProDataSet Attributes and Methods."

FILL returns true if successful and FALSE otherwise.